import { VideoPanel } from '@components/VideoPanel';

# Workspace

在 Agent TARS 的本地使用场景中，当前能够允许操作 File System 的目录即为 Workspace。

## 默认设定

为了避免影响你本地的文件系统，Workspace 的默认值为 `$pwd/agent-tars-workspace`，相当于增加了一层隔离，当你问 Agent TARS 能看到哪些文件：

```text
What files you can see?
```

因为是一个临时的目录，首次运行会为空：

![](/list-files.png)


## Custom Workspace

你可以通过 [CLI](./cli.mdx) 的 `--workspace` 参数来指定，如显示指定在当前目录：

```bash
agent-tars --workspace=./
```

假设当前目录为 [UI-TARS-desktop](https://github.com/bytedance/UI-TARS-desktop) 仓库，你将会看到如下输出：

![](/list-files-custom-workspace.png)


## Global Workspace

由于 Agent TARS 通常会安装到全局，因此，在全局安装的使用模式下，Agent TARS 还提供提供了一种通过统一的 Global Workspace 来管理 Config 和 File System 的便捷方式。

Global Workspace 会被创建在 `~/.agent-tars-workspace`，用于存储你的 Config 和 Files。

### 创建 Global Workspace

要初始化一个新的 Agent TARS workspace：

```bash
agent-tars workspace --init
```

这将启动一个交互式的创建过程：

<VideoPanel
  src="https://lf3-static.bytednsdoc.com/obj/eden-cn/zyha-aulnh/ljhwZthlaukjlkulzlp/docs/videos/create-workspace.mp4"
  loop
  autoPlay
/>

我们推荐你使用 TypeScript 来维护配置，这将帮助你将获得自动补全和类型检查的额外好处：

```typescript
// ~/.agent-tars-workspace/agent-tars.config.ts
import { defineConfig } from '@agent-tars/interface';

export default defineConfig({
  model: {
    provider: 'openai',
    id: 'gpt-4o',
    apiKey: 'your-api-key', // 使用环境变量更好
  },
});
```

---

### Global Workspace 的具体影响

当你完成 Global Workspace 的创建后，对你带来的具体影响是，无论你在什么目录下运行 `agent-tars`：

1. Global Workspace 中的 Config File 都将生效；
2. Agent 的 `workspace` 将会被设定为 `~/.agent-tars-workspace`；
3. File System 将指向 Global Workspace，也就是说，LLM 通过 File 工具输出的文件都将位于这个目录；
4. Agent TARS CLI 中一些依赖 File System 的能力也会指向这个目录，如 Snapshot。

你可以通过 Global Workspace 中的配置文件来自定义配置：

- `agent-tars.config.ts`（TypeScript，推荐）
- `agent-tars.config.json`（JSON）
- `agent-tars.config.yaml`（YAML）

---

### 打开 Global Workspace

要在 Visual Studio Code 中打开你的工作区：

```bash
agent-tars workspace --open
```

如果已安装 VS Code，这将启动 VS Code 并打开你的工作区文件夹。如果 VS Code 不可用，CLI 将提供有关如何手动打开工作区的说明。

---

### 临时禁用 Global Workspace

如果你在某次使用中，不期望依赖 Global Workspace 的配置，你可以选择临时禁用：

```bash
agent-tars workspace --disable
```

## FAQ

### 我可以有多个工作区吗？

`workspace` 命令在 `~/.agent-tars-workspace` 创建一个全局工作区。虽然你只能有一个全局工作区，但可以在不同的项目文件夹中创建和使用不同的配置，只需在运行其他命令时指定 `--workspace` 选项。

### 如何更新我的配置？

只需使用任何文本编辑器编辑工作区目录中的配置文件。如果你使用 TypeScript，请确保首先安装任何必要的依赖项。

### 我可以与其他人共享我的工作区吗？

是的！工作区只是一个包含配置文件的文件夹。你可以使用 Git 或任何其他版本控制系统共享它。只需确保排除包含敏感信息（如 API 密钥）的文件。

### 如果我删除了工作区会怎样？

你始终可以通过再次运行 `agent-tars workspace --init` 来重新创建工作区。但是，工作区中的任何配置或文件都将丢失，因此请确保备份重要文件。

### 如何指定不同的 API 密钥或模型提供商？

你可以：

1. 编辑你的工作区配置文件
2. 使用命令行选项在运行命令时覆盖设置：

```bash
agent-tars --model.provider openai --model.apiKey YOUR_API_KEY
```

### 如何在 CI/CD 管道中使用工作区？

对于持续集成环境，我们建议在你的项目中创建一个特定的工作区目录，并使用 `--workspace` 显式指定它，而不是依赖全局工作区。
